TeamOS Wiki

主题

Docs-as-Code 发布架构 ​

这是一页发布机制页，负责定义企业知识从 canonical wiki 到团队消费的完整链路。 它不负责证明为什么要选这个架构，决策依据应以下列页面为准： Docs-as-Code over Feishu Publishing、Feishu as Publishing Layer（已 superseded）。

它不负责定义涉及的实体本身，应引用： GitHub、VitePress、Multica。 （注：原架构选 Gitee，已被 GitHub 取代，详见 GitHub 实体页。）

状态 ​

当前 active 发布架构。 取代 飞书发布同步机制 成为企业知识的主发布通路。 飞书降格为可选浏览渠道，不再是真相源。

核心问题 ​

企业团队既要让 Hermes Agent 能稳定读取权威知识，又要让人类同事能方便浏览， 还要保留 review gate 的强约束 —— 怎么把这三件事统一在同一份 markdown 上？

答案是把整个 wiki/ 当代码仓来管：

markdown 是真相、git 是版本、Multica 是审批、ECS 工作副本是 runtime、VitePress 是 UI。

五个角色 ​

  1. GitHub — 真相源（github.com/daishiyu1991-hub/wiki-vault main 分支），二进制资产走 Git LFS
  2. ECS 工作副本 — /opt/wiki-vault/，canon/ 与 drafts/ 两区物理隔离
  3. Hermes Agents — 5 个容器，挂载 /wiki 只读，hermes-admin 多挂 /wiki-drafts 读写
  4. Multica — 评审 UI，审批通过事件触发 promote
  5. VitePress — 静态站渲染（含自研 wikilink 插件 把 <span class="wikilink-dead" title="未找到: xxx" style="color:#c33;border-bottom:1px dashed #c33">xxx</span> 转可点链接），nginx 服 wiki.86lux.net

完整链路 ​

text
[人] Obsidian 编辑 → vault-publish skill → git push (SSH) → GitHub wiki-vault main
                                                                ↓
                                                  ECS auto-rebuild cron (1min)
                                                                ↓
                              /opt/wiki-vault/canon/ ──→ VitePress build → wiki.86lux.net
                                                                ↓ ro 挂载
                                                           5 个 Hermes /wiki

[Agent] hermes-admin wiki-compile
        → 写入 /wiki-drafts/〈id〉-〈title〉.md
        → /opt/wiki-vault/drafts/
        → Multica 评审 UI 显示草稿
        → 人/Agent 在 UI 评论 + AI 改 + 点"通过"
        → 触发 promote.sh
        → git mv drafts/$F canon/$F + commit + push origin main
        → 回到真相源

Canon 与 Drafts 双区设计 ​

/opt/wiki-vault/canon/ 与 /opt/wiki-vault/drafts/ 通过 docker volume 的 ro/rw 隔离实现：

区谁能读谁能写用途
canon/5 个 Hermes（ro）+ VitePress（ro）+ promote.sh（rw via 宿主机）只有 promote.sh权威知识，agent 阅读基底
drafts/hermes-admin（rw）+ Multica（读）仅 hermes-admin候选知识，等待审批

物理隔离的意义：从文件系统层面阻止 agent 绕过 review gate 直接污染权威知识。

Promote 通路 ​

/opt/wiki-tools/promote.sh 是唯一允许写入 main 分支的入口：

sh
#!/bin/sh
# promote.sh <draft-filename>
set -e
FILE="$1"
cd /opt/wiki-vault
test -f "drafts/$FILE" || { echo "no such draft"; exit 1; }
git mv "drafts/$FILE" "canon/$FILE"
git commit -m "promote: $FILE"
git push origin main

触发方式（按优先级）：

  1. 首选：Multica 后端审批通过事件 → webhook → docker exec hermes-admin /opt/wiki-tools/promote.sh "$file"
  2. 降级：让 Multica 把"通过"消息发给 hermes-admin chat，由 agent 调一个 wrap 了 promote.sh 的 skill
  3. 兜底：admin 手工 ssh 到 ECS 跑 promote.sh

同步节奏 ​

  • auto-rebuild cron：* * * * *（每分钟），脚本 /opt/wiki-tools/auto-rebuild.sh
    • 用 flock 防并发
    • git fetch 比对 LOCAL 与 origin/main，无新 commit 直接退出（无负载）
    • 有新 commit 则 git pull --ff-only → refresh-symlinks.sh → npx vitepress build docs
    • 日志写到 /var/log/wiki-rebuild.log
  • promote 触发：事件驱动，无固定节奏（Multica 审批通过 → webhook → promote.sh）

历史上曾分两条 cron（wiki-sync */5 + build */5 错峰），2026-04-17 起合并为一条 auto-rebuild *， 端到端延迟从 5-7 分钟缩短到 1-2 分钟。

与既有规则的关系 ​

完成判据（已全部达成 2026-04-17） ​

  1. ✅ GitHub daishiyu1991-hub/wiki-vault 仓存在且 main 有完整 vault
  2. ✅ ECS /opt/wiki-vault/canon/ 与 GitHub 一致（auto-rebuild cron 每分钟同步）
  3. ✅ 5 个 hermes 容器 cat /wiki/系统总览.md 可读
  4. ✅ https://wiki.86lux.net 可访问、HTTPS 生效、wikilink 可点击跳转（自研 wikilink 插件）
  5. ✅ wiki-compile 草稿落到 /opt/wiki-vault/drafts/
  6. ✅ Multica 点通过 → 1-2min 内全链路同步
  7. ✅ Git LFS 已配（.gitattributes 跟踪 png/jpg/mp4/pdf/...），冒烟测试通过
  8. ✅ 本地 vault E:\Ai+人协作系统\wiki\ 已升级为 git clone，与 ECS 100% 同源

关联 ​

TeamOS · docs as code · canon=权威知识，drafts=候选区

© 86lux.net